Filtering

Filtering allows you search for records within a connection. If you wanted to find all resources who's names start with Projector, you can issue the following request:

query {
  resources(filters: [
    {field: name, operation: like, value: "Projector%"}
  ]) {
    edges {
      node {
        name
      }
    }
  }
}

Operations

The type FilterOperation defines what operations we are able to use between fields and values. You can think of them as functions that each node is passed through. Each operation has its own semantics, and are explained here for clarity.

Singular

These operations work on a singular field value and take in a singular value. They have type <T>(field: T, value: T) -> bool

The following are the "standard" operations that map nicely to existing operations in logic and programming. The table shows the operation or function to be used with the same value you would pass to "operation", the symbol this most maps to in logic, and its meaning.

Singular String Operations

These operate on strings and are still singular.

LIKE

like: "~" Match the value against a field. Use % for the wildcard.

eg:

query findMatchingAccounts {
  accounts(filters: {field:name operation:like value:"%Adm%"}) {
    edges {
      node {
        id
        name
      }
    }
  }
}

WORDLIKE

wordlike: "~" Match a word or an ordered expression while excluding punctuations and case sensitivity.

eg:

query findMatchingAccounts {
  accounts(filters: {field:name operation:wordlike value:"Admin"}) {
    edges {
      node {
        id
        name
      }
    }
  }
}

If you have multiple words in the value, they must appear in that order in the field to match.

Hybrid

These operations work on a singular field value and take in a list of values. They have type <T>(field: T, values: List[T]) -> bool

IN

in: IN Matches if the field value equals any in the provided list of values

eg:

"a" in ["a", "p", "l", "e"] => true
5 in [1,2,3,4,5] => true
"target" in ["missing", "value"] => false

NOTIN

notin: NOT IN Excludes if the field value equals any in the provided list of values

eg:

"a" in ["a", "p", "l", "e"] => false
5 in [1,2,3,4,5] => false
"target" in ["missing", "value"] => true

Plural

Plural operations (of which we only have one) work on fields that are themselves lists, and require a list of values to be provided. It has type <T>(field: List[T], values: List[T]) -> bool

This is equivalent to computing if the intersection of field and values is non empty: field_values ∩ values != ∅.

CONTAINS

contains: ANY IN Matches if any value from the field is in the provided values list

Allergy Example

Consider an imaginary dataset containing three items:

[
  {"id": 1, "name": "Sean", "allergies": ["onions", "tomatoes", "grass"]},
  {"id": 2, "name": "Gavin", "allergies": ["peanuts", "gluten"]},
  {"id": 1, "name": "Carl", "allergies": ["peanuts"]},
  {"id": 1, "name": "Tommaso", "allergies": ["cats", "dairy"]},
]

We want to figure out what we can cook with, so we query anyone with either a peanut or onion allergy, using contains:

query knownAllergies {
  people(filters: {field:allergies operation:contains values:["peanuts", "onions"]}) {
    id
    name
    allergies
  }
}

This would return everyone. Let's just focus in on some examples where the values change:

allergies contains ["peanuts", "onions"] => [Sean, Gavin, Carl]
allergies contains ["gluten"] => [Gavin]
allergies contains ["dairy", "grass"] => [Sean, Tommaso]
allergies contains ["peanuts"] => [Gavin, Carl]
allergies contains ["tomatoes", "gluten"] => [Sean, Gavin]
allergies contains ["yeast"] => []

Core GraphQL Custom Field Example

An example of a contains query in Core GraphQL would be filtering Custom Fields by what entities they have.

query filteredCustomFields {
  customFields(filters: {
    field:entities
    operation:contains
    values:["Account", "Contact"]
  }) {
    edges {
      node {
        label      
        entities { name }
      }
    }
  }
}

This will return custom fields that are set up for Accounts or Contacts, regardless of any other entities the custom field is set up for.